<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Introduction</title>
<link rel="stylesheet" href="../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Math Toolkit 4.1.0">
<link rel="up" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">
<link rel="prev" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">
<link rel="next" href="reference.html" title="Reference">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../fp_facets.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_facets.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.fp_facets.facets_intro"></a><a class="link" href="facets_intro.html" title="Introduction">Introduction</a>
</h3></div></div></div>
<h6>
<a name="math_toolkit.fp_facets.facets_intro.h0"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.the_problem"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.the_problem">The
        Problem</a>
      </h6>
<p>
        The C++98 standard does not specify how <span class="emphasis"><em>infinity</em></span> and
        <span class="emphasis"><em>NaN</em></span> are represented in text streams. As a result, different
        platforms use different string representations. This can cause undefined
        behavior when text files are moved between different platforms. Some platforms
        cannot even input parse their own output! So 'route-tripping' or loopback
        of output to input is not possible. For instance, the following test fails
        with MSVC:
      </p>
<pre class="programlisting"><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span>
<span class="keyword">double</span> <span class="identifier">inf</span> <span class="special">=</span> <span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">();</span>
<span class="keyword">double</span> <span class="identifier">r</span><span class="special">;</span>
<span class="identifier">ss</span> <span class="special">&lt;&lt;</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</span>
<span class="identifier">ss</span> <span class="special">&gt;&gt;</span> <span class="identifier">r</span><span class="special">;</span> <span class="comment">// Read back in.</span>

<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"infinity output was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">inf</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1.#INF</span>
<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"infinity input was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">r</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1</span>

<span class="identifier">assert</span><span class="special">(</span><span class="identifier">inf</span> <span class="special">==</span> <span class="identifier">y</span><span class="special">);</span> <span class="comment">// Fails!</span>
</pre>
<h6>
<a name="math_toolkit.fp_facets.facets_intro.h1"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.the_solution"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.the_solution">The
        Solution</a>
      </h6>
<p>
        The facets <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
        and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> format
        and parse all floating-point numbers, including <code class="computeroutput"><span class="identifier">infinity</span></code>
        and <code class="computeroutput"><span class="identifier">NaN</span></code>, in a consistent
        and portable manner.
      </p>
<p>
        The following test succeeds with MSVC.
      </p>
<pre class="programlisting"><span class="identifier">locale</span> <span class="identifier">old_locale</span><span class="special">;</span>
<span class="identifier">locale</span> <span class="identifier">tmp_locale</span><span class="special">(</span><span class="identifier">old_locale</span><span class="special">,</span> <span class="keyword">new</span> <span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
<span class="identifier">locale</span> <span class="identifier">new_locale</span><span class="special">(</span><span class="identifier">tmp_locale</span><span class="special">,</span> <span class="keyword">new</span> <span class="identifier">nonfinite_num_get</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
</pre>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top">
<p>
          To add two facets, <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
          and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>,
          you may have to add one at a time, using a temporary locale.
        </p>
<p>
          Or you can create a new locale in one step
        </p>
<p>
          <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span> <span class="identifier">new_locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_get</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;));</span></code>
        </p>
<p>
          and, for example, use it to imbue an input and output stringstream.
        </p>
</td></tr>
</table></div>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
          To just change an input or output stream, you can concisely write <code class="computeroutput"><span class="identifier">cout</span><span class="special">.</span><span class="identifier">imbue</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;));</span></code> or <code class="computeroutput"><span class="identifier">cin</span><span class="special">.</span><span class="identifier">imbue</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_get</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;));</span></code>
        </p></td></tr>
</table></div>
<pre class="programlisting"><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span>
<span class="identifier">ss</span><span class="special">.</span><span class="identifier">imbue</span><span class="special">(</span><span class="identifier">new_locale</span><span class="special">);</span>
<span class="keyword">double</span> <span class="identifier">inf</span> <span class="special">=</span> <span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">();</span>
<span class="identifier">ss</span> <span class="special">&lt;&lt;</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</span>
<span class="identifier">BOOST_MATH_ASSERT</span><span class="special">(</span><span class="identifier">ss</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"inf"</span><span class="special">);</span>
<span class="keyword">double</span> <span class="identifier">r</span><span class="special">;</span>
<span class="identifier">ss</span> <span class="special">&gt;&gt;</span> <span class="identifier">r</span><span class="special">;</span> <span class="comment">// Read back in.</span>
<span class="identifier">BOOST_MATH_ASSERT</span><span class="special">(</span><span class="identifier">inf</span> <span class="special">==</span> <span class="identifier">r</span><span class="special">);</span> <span class="comment">// Confirms that the double values really are identical.</span>

<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"infinity output was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ss</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"infinity input was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">r</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
<span class="comment">// But the string representation of r displayed will be the native type</span>
<span class="comment">// because, when it was constructed, cout had NOT been imbued</span>
<span class="comment">// with the new locale containing the nonfinite_numput facet.</span>
<span class="comment">// So the cout output will be "1.#INF on MS platforms</span>
<span class="comment">// and may be "inf" or other string representation on other platforms.</span>
</pre>
<h5>
<a name="math_toolkit.fp_facets.facets_intro.h2"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.c_0x_standard_for_output_of_infi"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.c_0x_standard_for_output_of_infi">C++0X
        standard for output of infinity and NaN</a>
      </h5>
<p>
        <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3242.pdf" target="_top">C++0X
        (final) draft standard</a> does not explicitly specify the representation
        (and input) of nonfinite values, leaving it implementation-defined. So without
        some specific action, input and output of nonfinite values is not portable.
      </p>
<h5>
<a name="math_toolkit.fp_facets.facets_intro.h3"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.c99_standard_for_output_of_infin"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.c99_standard_for_output_of_infin">C99
        standard for output of infinity and NaN</a>
      </h5>
<p>
        The <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99
        standard</a> <span class="bold"><strong>does</strong></span> specify how infinity
        and NaN are formatted by printf and similar output functions, and parsed
        by scanf and similar input functions.
      </p>
<p>
        The following string representations are used:
      </p>
<div class="table">
<a name="math_toolkit.fp_facets.facets_intro.c99_representation_of_infinity_a"></a><p class="title"><b>Table 2.1. C99 Representation of Infinity and NaN</b></p>
<div class="table-contents"><table class="table" summary="C99 Representation of Infinity and NaN">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  number
                </p>
              </th>
<th>
                <p>
                  string
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  Positive infinity
                </p>
              </td>
<td>
                <p>
                  "inf" or "infinity"
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Positive NaN
                </p>
              </td>
<td>
                <p>
                  "nan" or "nan(...)"
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative infinity
                </p>
              </td>
<td>
                <p>
                  "-inf" or "-infinity"
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative NaN
                </p>
              </td>
<td>
                <p>
                  "-nan" or "-nan(...)"
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        So following C99 provides a sensible 'standard' way of handling input and
        output of nonfinites in C++, and this implementation follows most of these
        formats.
      </p>
<h6>
<a name="math_toolkit.fp_facets.facets_intro.h4"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.signaling_nans"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.signaling_nans">Signaling
        NaNs</a>
      </h6>
<p>
        A particular type of NaN is the signaling NaN. The usual mechanism of signaling
        is by raising a floating-point exception. Signaling NaNs are defined by
        <a href="http://en.wikipedia.org/wiki/IEEE_floating-point_standard" target="_top">IEEE
        754-2008</a>.
      </p>
<p>
        Floating-point values with layout <span class="emphasis"><em>s</em></span>111 1111 1<span class="emphasis"><em>a</em></span>xx
        xxxx xxxx xxxx xxxx xxxx where <span class="emphasis"><em>s</em></span> is the sign, <span class="emphasis"><em>x</em></span>
        is the payload, and bit <span class="emphasis"><em>a</em></span> determines the type of NaN.
      </p>
<p>
        If bit <span class="emphasis"><em>a</em></span> = 1, it is a quiet NaN.
      </p>
<p>
        If bit <span class="emphasis"><em>a</em></span> is zero and the payload <span class="emphasis"><em>x</em></span>
        is nonzero, then it is a signaling NaN.
      </p>
<p>
        Although there has been theoretical interest in the ability of a signaling
        NaN to raise an exception, for example to prevent use of an uninitialised
        variable, in practice there appears to be no useful application of signaling
        NaNs for most current processors. <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3242.pdf" target="_top">C++0X
        18.3.2.2</a> still specifies a (implementation-defined) representation
        for signaling NaN, and <code class="computeroutput"><span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keyword">bool</span> <span class="identifier">has_signaling_NaN</span></code> a method of checking
        if a floating-point type has a representation for signaling NaN.
      </p>
<p>
        But in practice, most platforms treat signaling NaNs in the same as quiet
        NaNs. So, for example, they are represented by "nan" on output
        in <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99</a>
        format, and output as <code class="computeroutput"><span class="number">1.</span><span class="special">#</span><span class="identifier">QNAN</span></code> by Microsoft compilers.
      </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
          The C99 standard does not distinguish between the quiet NaN and signaling
          NaN values. A quiet NaN propagates through almost every arithmetic operation
          without raising a floating-point exception; a signaling NaN generally raises
          a floating-point exception when occurring as an arithmetic operand.
        </p>
<p>
          C99 specification does not define the behavior of signaling NaNs. NaNs
          created by IEC 60559 operations are always quiet. Therefore this implementation
          follows C99, and treats the signaling NaN bit as just a part of the NaN
          payload field. So this implementation does not distinguish between the
          two classes of NaN.
        </p>
</td></tr>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
          An implementation may give zero and non-numeric values (such as infinities
          and NaNs) a sign or may leave them unsigned. Wherever such values are unsigned,
          any requirement in the C99 Standard to retrieve the sign shall produce
          an unspecified sign, and any requirement to set the sign shall be ignored.
        </p>
<p>
          This might apply to user-defined types, but in practice built-in floating-point
          types <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
          <span class="keyword">double</span></code> have well-behaved signs.
        </p>
</td></tr>
</table></div>
<p>
        The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>,
        <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
        <span class="keyword">double</span></code>. An optional + sign can be
        used with positive numbers (controlled by ios manipulator <code class="computeroutput"><span class="identifier">showpos</span></code>).
        The function <code class="computeroutput"><span class="identifier">printf</span></code> and similar
        C++ functions use standard formatting flags to put all lower or all upper
        case (controlled by <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios</span></code> manipulator <code class="computeroutput"><span class="identifier">uppercase</span></code>
        and <code class="computeroutput"><span class="identifier">lowercase</span></code>).
      </p>
<p>
        The function <code class="computeroutput"><span class="identifier">scanf</span></code> and similar
        input functions are case-insensitive.
      </p>
<p>
        The dots in <code class="computeroutput"><span class="identifier">nan</span><span class="special">(...)</span></code>
        stand for an arbitrary string. The meaning of that string is implementation
        dependent. It can be used to convey extra information about the NaN, from
        the 'payload'. A particular value of the payload might be used to indicate
        a <span class="emphasis"><em>missing value</em></span>, for example.
      </p>
<p>
        This library uses the string representations specified by the C99 standard.
      </p>
<p>
        An example of an implementation that optionally includes the NaN payload
        information is at <a href="http://publib.boulder.ibm.com/infocenter/zos/v1r10/index.jsp?topic=/com.ibm.zos.r10.bpxbd00/fprints.htm" target="_top">AIX
        NaN fprintf</a>. That implementation specifies for Binary Floating Point
        NANs:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            A NaN ordinal sequence is a left-parenthesis character '(', followed
            by a digit sequence representing an integer n, where 1 &lt;= n &lt;=
            INT_MAX-1, followed by a right-parenthesis character ')'.
          </li>
<li class="listitem">
            The integer value, n, is determined by the fraction bits of the NaN argument
            value as follows:
          </li>
<li class="listitem">
            For a signalling NaN value, NaN fraction bits are reversed (left to right)
            to produce bits (right to left) of an even integer value, 2*n. Then formatted
            output functions produce a (signalling) NaN ordinal sequence corresponding
            to the integer value n.
          </li>
<li class="listitem">
            For a quiet NaN value, NaN fraction bits are reversed (left to right)
            to produce bits (right to left) of an odd integer value, 2*n-1. Then
            formatted output functions produce a (quiet) NaN ordinal sequence corresponding
            to the integer value n.
          </li>
</ul></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
          This implementation does not (yet) provide output of, or access to, the
          NaN payload.
        </p></td></tr>
</table></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../fp_facets.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_facets.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
